\documentclass[a4paper,10pt]{article}
\usepackage[utf8x]{inputenc}
\usepackage[cm]{fullpage}

%opening
\title{Course Diary - Entry \#5\\
475 Advanced Topics in Software Engineering}
\author{Eli Gutin \texttt{eg08}, \\ Michael Kwan \texttt{mk08}, \\ John Wong \texttt{jw808} }

\begin{document}

\maketitle

\section{Three key points from the lecture}

\begin{itemize} 
\item{
Some software projects fail and others succeed under pressure. We learned what the differentiating factors are and how one can move a project in a positive direction when it's in trouble. Processes must be in place to organize the lifecycle of the project. If not, this can in the worst case lead to stress and chaos.  At the same time one needs to a achieve a balance; some rules, standard procedures but not too much bureaucracy as too much of the latter can stifle productivity.
}
\item{
Requirements gathering is critical stage in the project lifecycle.
One must strive for concrete requirements and cut out the non-essential information and document them.
At the same time we need to be prepared for change in requirements.  Analysis is another vital phase.
We need to form a conceptual model of the system and work through the steps. At the same time, one mustn't try to do everything at once, not get requirements and do too much analysis known as "Analysis paralysis".
It's advisable to listen to the language of domain experts (Radio DJs, traders etc.)
}
\item{
Coding is fun but one must unit test always! It's the professional thing to do.
It's also important to code according to horizontal and vertical slices. This means to get tangible results quickly to give confidence (to management) and build momentum but also without compromising the structure and design and working too much. A vertical slice is an end-to-end story (doesn't have all functionality) but demonstrates one particular use-case or story. The horizontal slice expands on the richness of functions and flexibility. Another useful technique is 'timeboxing' which means to organize tasks into \emph{MoSCoW}, musts, could, should. Musts can only 50\% of the timebox time. never more than 40-50 %. It's important to manage the client's expectations \emph{DO NOT} promise them everything under the sun and clearly explain what each iteration will deliver.
}
\end{itemize}

\section{Related Reading}
We found an interesting article from the IEEE: \texttt{http://spectrum.ieee.org/computing/software/why-software-fails}. There it started off by describing a catastrophic failure at a familiar company \textit{Sainsbury's}  where a glitch in one of the automated distribution systems resulted in the virtual 'disappearance' of a warehouse and as a result, goods were being routed somewhere else.  It then remarked that these failures happen in many different kinds of organizations, across a broad spectrum; all the way from commerical, to non-profit organizations and this occurs all over the world. It then gave common reasons, which agreed with what was told in the lecture: unrealistic or poorly articulated goals, bad estimates of required resources and host of other causes. The article claimed that most fail for more than just one or two of these - usually several. This article reinforced the principles that we learned in the lectures as it gave many cases of project failure and identified common causes.

There was an online article that spelled out clearly the benefits of using vertical slices, \\ \texttt{http://brendan.enrick.com/post/we-slice-software-vertically-just-like-bread.aspx} . This one 
made clear why a vertical slice offers many advantages over just working on one layer at a time. It also made us realise how common it is to want to start finishing each layer of an application in turn and why this is usually not so great. We also feel that these ideas are very similar and connected to those expressed in this source 
\\ \texttt{http://c2.com/xp/YouArentGonnaNeedIt.html} because by only working on horizontal slices
you develop what you think you need rather than what's explicitly needed which is an anti-pattern according to both of these sources.
% ******************* Write about atleast 2 or 3 of these **************************
% http://www.hyperthot.com/pm_sdm.htm
% http://www.cs.toronto.edu/~sme/papers/2000/ICSE2000.pdf
% http://www.techiwarehouse.com/engine/18a41ffa/Software-Engineering-Phases
% http://msdn.microsoft.com/en-us/library/windows/desktop/cc307416.aspx
% http://www.goodreads.com/author/show/481931.Richard_Whitehead

\section{Similar Past Projects}
\subsection{Mike's experience}
During my industrial placement, I encountered vertical slicing when asked to present ideas to management at early stages of the SLC. Even 
though I had not realised the formal term, I essentially performed vertical slicing to produce a skeleton which showed approximate functionality 
without fleshing it out fully.

\subsection{Eli's experience}
For my group project last year we were experiencing delays in delivering the final product. At that time we had to use a technique similar to timeboxing wherein we prioritized tasks according musts, coulds and shoulds. That ensured that we manage to at least deliver the core requirements in time.
\subsection{John's experience}
I was solely responsible for a web project in my industrial placement. 
Because of few specific objectives to initiate my planning process, I started off by making some related features in order to gain useful feedback and to understand the exact requirements. 
I then gathered that information to build a conceptual model of the project to help organise my development approaches.

\section{Tutorial Exercise Description}
The tutorial exercise consisted of an application which aims to aggregate weather information from multiple sources for a selected city and 
generate a report based off of the average. We were required to create a vertical slice of this system to demonstrate end-to-end functionality. 
The aim is to start with an expedient implementation providing dummy weather data and to establish code interfaces from this. After this, we 
needed to create the horizontal slice, swapping out the expedient implementation for a 'good' implementation which read from files on the local 
disk or performed web scraping.

\section{Main Challenges}
Unlike the previous tutorials, the existing codebase on this exercise was small and it took some 
effort to create good class and package hierarchies, as well as to determine the sort of interfaces 
various parts of the code should expose. Another challenge we faced was that we forced ourselves to 
use TDD as taught previously. It was tough to get into the habit of writing failing tests first, especially 
at times when we already had a good idea of the code and structure we wanted.

\section{Approaches}
Given that we are creating a vertical slice of a project which has potentially unstable requirements, 
we aimed to write some basic end-to-end features and make them extensible. We used TDD as it allows for writing code quickly that we have confidence in.

We started by creating classes to encapsulate appropriate objects, i.e. \texttt{City} and \texttt{WeatherData}, overriding relevant methods such as 
\texttt{equals}, \texttt{hashCode} and \texttt{toString}. Even though, for the current implementation 
it would have been sufficient to treat the above as a \texttt{String} and \texttt{Double} respectively, we considered the possibility that 
more information on each might be stored in the future. We then set up a \texttt{CitySourceImpl} class which returned a list of dummy cities. 
Similarly, we created a \texttt{WeatherSourceImpl} class which held queryable mappings from \texttt{City} to randomly generated \texttt{WeatherData} objects 
(\texttt{Map<City, WeatherData>}). The next step was to extract the original contents of \texttt{setText} in the GUI (i.e. \texttt{"In " + city + " on " + date ...}) to a new class, 
\texttt{ReportGenerator}. This was done to divide up the responsibilities among collaborators. This new class is constructed with an instance of \texttt{ICitySource} and a collection of \texttt{IWeatherSource} objects - 
coding against the interface enables easier unit testing and mocking of the 'sources'. The \texttt{ReportGenerator} also deals with the averaging 
of \texttt{WeatherData} obtained from the various \texttt{WeatherSource} objects passed in as well as the generation of the report string.

In our implementation, we instantatiate \texttt{ReportGenerator} at the start (in reality, we would put the GUI in a separate package and pass in the 
\texttt{ReportGenerator} to fully abstract it). The GUI then simply fetches the list of available cities from \texttt{ICitySource} 
(which would also ideally be passed in via some form of dependency injection) to initialise its combo then queries \texttt{ReportGenerator} for reports. 
Hence the concept of \texttt{WeatherData} and multiple \texttt{WeatherSourceImpl}s is completely abstracted from the GUI.

Having set up the structure of the code, implementing the \texttt{WeatherSourceImpl}, \texttt{CitySourceImpl} to read from real data was trivial. We 
created text files which had their paths passed in as \texttt{main} arguments, which were then parsed and tokenised with standard Java file IO APIs contained in 
\texttt{InputStream} and \texttt{BufferedReader}. Given that the content format was different for the two sources, we implemented the file parsing code 
independently. The structure of our code allowed us to preserve the interfaces we defined before and simply to change the concrete implementation details.

Since we had been using a TDD approach throughout the implementation, by the time we finished, we left behind a comprehensive test suite. A typical example of 
the kind of test we wrote is \texttt{testDataAverager} which mocked out an \texttt{IWeatherSource} to return dummy \texttt{WeatherData} objects and tested the 
data was appropriately averaged by \texttt{ReportGenerator}.

\section{Feedback on the lecture/excercise}
We felt the layout of the lecture was fluid, with information presented in detail. Each section started off highlighting relevant common problems and 
situations which occur in an industrial environment, and then followed with some tactics and guidelines to counter these pre-emptively. The lecture 
included several case studies to reinforce the ideas and raise awareness of pitfalls in certain scenarios. We found these helped consolidate the concepts 
outlined in each section.

The aims and requirements for the exercise were clearly listed and the guidelines were straightforward.
\end{document}
